/*!
  \copyright  Copyright (c) 2023 Qualcomm Technologies International, Ltd.
              All Rights Reserved.
              Qualcomm Technologies International, Ltd. Confidential and Proprietary.
  \file       storage_manager.h
  \defgroup   storage_manager Storage Manager
  @{

    \ingroup domains
    \brief      The storage manager APIs
*/

#ifndef STORAGE_MANAGER_H_
#define STORAGE_MANAGER_H_

#include "storage_manager_types.h"

typedef struct storage_manager_event_if
{
	/*!
      \brief Is invoked before closing a buffer. 
      \see StorageManager_ForceCloseAllBuffers, StorageManager_ForceCloseAllBuffersOfStorage
      \param handle[in] The buffer closed immediately after this callback.
    */
    void (*OnForceCloseBuffer) (storage_mgr_buffer_handle_t handle);
} storage_mgr_event_if;

/*!
  \brief Opens a buffer in the storage medium
  \param config[in] The storage configuration to open the buffer with.
  \param event_if[in] The user callback to receive event indications
  \return The buffer handle if opened successfully, NULL otherwise.
*/
storage_mgr_buffer_handle_t StorageManager_OpenBuffer(storage_mgr_config_data_t config, const storage_mgr_event_if * event_if);

/*!
  \brief Loads from storage
  \param source[in] The handle of the storage buffer to load from.
  \param offset[in] The starting position in bytes to load from.
  \param dest[in,out] The buffer to write the data.
  \param bytes[in] The amount of data to load/read.
  \return TRUE if the data loaded successfully, FALSE otherwise.
*/
bool StorageManager_LoadData(storage_mgr_buffer_handle_t source, uint32 offset, uint8 * dest, size_t bytes);

/*!
  \brief Saves data to storage
  \param dest[in] The handle of the storage buffer to save the data.
  \param offset[in] The starting position in bytes to save from.
  \param source[in,out] The buffer to read the data from.
  \param bytes[in] The amount of data to save/write.
  \return TRUE if the data was saved successfully, FALSE otherwise.
*/
bool StorageManager_SaveData(storage_mgr_buffer_handle_t dest, uint32 offset, const uint8 * source, size_t bytes);

/*!
  \brief Closes a buffer in the storage medium and \b invalidates the handle (doesn't set to NULL)
  \param buffer[in] The handle of the storage buffer to close.
  \warning Will PANIC if unable to close buffer
*/
void StorageManager_CloseBuffer(storage_mgr_buffer_handle_t buffer);

/*!
  \brief Closes all the buffers held by the storage type.  
  \param type[in] The type of storage \see storage_manager_storage_type_t.
  \warning Will PANIC if unable to close buffer. However, calling this API when there's nothing to close, i.e., no open buffers, is valid.
  \note The handle-owners are informed about the closure through a callback, if present, as a 'last chance' to interact with the buffer.
  \see storage_manager_event_if
*/
void StorageManager_ForceCloseAllBuffersOfStorage(storage_mgr_type_t type);

/*!
  \brief Closes all the buffers held by the storage manager and all types therein.
  \warning Will PANIC if unable to close buffer. However, calling this API when there's nothing to close, i.e., no open buffers, is valid.
  \note The handle-owners are informed about the closure through a callback, if present, as a 'last chance' to interact with the buffer.
  \see storage_manager_event_if
*/
void StorageManager_ForceCloseAllBuffers(void);

/*!
  \brief Get buffer size
  \param buffer[in] The handle of the storage buffer.
  \return size in bytes.
*/
size_t StorageManager_GetBufferSize(storage_mgr_buffer_handle_t buffer);

/*! @} */

#endif /* STORAGE_MANAGER_H_ */